MarkLogic Server 11.0 Product Documentation
POST /v1/values/{name}

Summary

Query the values in a lexicon or range index, or find co-occurrences of values in multiple range indexes. Optionally apply an aggregate function to the values or co-occurrences. Query and query options are passed in the POST body.

URL Parameters
q? A string query. For details, see Automatic Query Text Parsing and Grammar in the Search Developer's Guide. This query is AND'd with the query(s) in the request body.
options? The name of query options previously created via a PUT or POST request to the /v1/config/query service.
database? Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the "eval-in" privilege; for details, see Security Requirements in the REST Application Developer's Guide.
view? The view of the query results to return in the response. Accepted values: values, aggregate, all. Default: all.
format? You can use this parameter in conjunction with or instead of the request Content-type and Accept headers to indicate the input and/or output content type. The Content-type header takes precedence over format in most cases. format takes precedence over the Accept header in most cases. For details, see Controlling Input and Output Content Type in the REST Application Developer's Guide. Accepted values: json or xml.
txid? The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
collection* Filter results to include only matches in the named collection. If you specify this parameter multiple times, the collections are OR related.
direction? The sort order of returned results. Accepted values: ascending or descending. The default direction depends on the sort order defined in the options. The default is ascending for item-order and descending for frequency-order.
directory? Filter results to include only matches from documents in the specified database directory.
frequency? The method of calculating frequency. Accepted values: item (default) or fragment. Fragment frequency returns the number of fragments with an included value. Item frequency returns the total number occurrences of an included value.
limit? The maximum number of values or tuples to retrieve from the lexicon. Default: No limit.
start? The index of the first result to return from the subset defined by limit. Results are numbered beginning with 1. Default: 1.
pageLength? The number of values to return within the subset of values defined by limit, beginning with the value selected by start. Default: Return all selected values.
aggregate? The name of a built-in or user-defined aggregate function to run against the lexicon. If the function is not a built-in aggregate, you must also supply aggregatePath. The supported builtin aggregate functions are: sum, avg, min, max, median, count, stddev, stddev-population, correlation, covariance, covariance-population, variance, variance-population.
aggregatePath? The path to the native plugin library containing the implementation of the function named by the aggregate function. If the path is empty or is not specified, a built-in aggregate is assumed.
transform? Names a search result transformation previously installed via the /transforms service. The transformation is applied to the <search:response/> after applying user-defined transforms defined in the query options using <transform-results>. For details, see Transforming the Search Response in the REST Application Developer's Guide.
trans:{name}* A transform parameter name and value. For example, trans:myparam=1. Transform parameters are passed to the transform named in the transform parameter.
timestamp? A timestamp returned in the ML-Effective-Timestamp header of a previous request. Use this parameter to iteratively fetch results based on the contents of the database at a fixed point-in-time. For more details, see Performing Point-in-Time Operations in the REST Application Developer's Guide.
forest-name* The name of forest(s) to which results should be limited. The forest(s) must exist in the database for this request. If you wish to retrieve results from multiple specific forests, specify this parameter once per forest.
Request Headers
Accept* The expected MIME type of the data in the response. Accepted types: application/json or application/xml. Setting the format parameter overrides this header. For details, see Controlling Input and Output Content Type in the REST Application Developer's Guide.
Content-Type The MIME type of the data in the POST body. Accepted values: application/json or application/XML. For details, see Controlling Input and Output Content Type in the REST Application Developer's Guide.
Response Headers
Content-type The MIME type of the data in the response. The results will be in either XML or JSON, depending upon the value of the format parameter or the Accept header.
ML-Effective-Timestamp The system timestamp at which this operation was performed. You can use the value in the timestamp parameter of a subsequent request. For more details, see Performing Point-in-Time Operations in the REST Application Developer's Guide.

Response

On success, MarkLogic Server responds with a 200 status and the query results in the response body.

If you use an aggregate function and the target lexicon type does not support the chosen operation, such as stddev on a string valued lexicon, or if the aggregate function does not exist, MarkLogic Server responds with a 400 (Bad Request) status, with additional error information in the response body.

Required Privileges

This operation requires the rest-reader role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-reader

Usage Notes

The {name} portion of the URL must match the name of a values or tuples specification in the in-scope query options (in the POST body, in persistent query options or in the default query options). See below for details on how the in-scope query options are determined.

Use a query in the q request parameter and/or the request body to limit the returned values to those occurring in fragments that match the query. For details, see Using a Query to Constrain Results in the REST Application Developer's Guide.

The request body must contain either a structured query (a serialized representation of a search:query), a serialized cts:query, or a combined query (a serialized representation of a search:search), expressed as either XML or JSON. For details, see Searching Using Structured Queries in the Search Developer's Guide and Specifying Dynamic Query Options with Combined Query in the REST Application Developer's Guide.

The format parameter always overrides the Accept header and can be used as a fallback for the Content-type header. For details, see Controlling Input and Output Content Type in the REST Application Developer's Guide. If you do not use the format parameter or an Accept header, an XML response is returned.

Supply query options with the options request parameter or in the request body. If no query options are specified in either the request parameter or the request body, MarkLogic Server uses the configured default options. If no default options are configured, MarkLogic Server uses the default Search API options.

If the body contains a structured query or a cts:query, use the options request parameter to specify custom query options. If the body contains a combined query, use the options request parameter and/or the options component of the combined query.

If query options are supplied in both the options request parameter and the request body, the options are merged together. In cases of conflict, an option definition in the combined query overrides the one in the persistent options. Constraints defined in both option sources are preserved; in the event of a constraint name collision, the constraint defined in the request body takes precedence.

Query options named in the options request parameter must be pre-installed using the /config/query service.

When you apply a builtin or user defined aggregate function, the output is dependent on the function. For details, see Analyzing Lexicons and Range Indexes With Aggregate Functions in the REST Application Developer's Guide.

See Also

Example

Assume the following query options are installed with the name "index-options":

<options xmlns="http://marklogic.com/appservices/search">
    <values name="speaker">
        <range type="xs:string">
            <element ns="" name="SPEAKER"/>
        </range>
    </values>
</options>

$ cat query.xml
<query xmlns="http://marklogic.com/appservices/search">
  <near-query>
    <term-query>
      <text>Yorick</text>
    </term-query>
    <term-query>
      <text>Horatio</text>
    </term-query>
  </near-query>
</query>

$ curl --anyauth --user user:password -X POST -d@./query.xml \
    -H "Content-type: application/xml" -i \
    http://localhost:8000/v1/values/speaker?options=index-options

==> The distinct values of the SPEAKER element in element range index, for
    fragments that match the query "Yorick NEAR Horatio", expressed as a
    structured query in the POST body. The results are returned as XML.

HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 827
Connection: Keep-Alive
Keep-Alive: timeout=5

<values-response name="speaker" type="xs:string" 
    xmlns="http://marklogic.com/appservices/search" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  ...
  <distinct-value frequency="1">HAMLET</distinct-value>
  <distinct-value frequency="1">HORATIO</distinct-value>
  <distinct-value frequency="1">KING CLAUDIUS</distinct-value>
  ...
  <metrics>
    <values-resolution-time>PT0.001943S</values-resolution-time>
    <total-time>PT0.003052S</total-time>
  </metrics>
</values-response>

Example

Assume the following query options are installed with the name "index-options":

{
  "options": {
    "values": [
      {
        "name": "speaker",
        "range": {
          "type": "xs:string",
          "element": { "ns": "", "name": "SPEAKER" }
        }
      }
    ]
  }
}

$ cat query.json
{
  "query" : {
    "near-query" : {
      "term-query" : [ {"text" : "Yorick"}, {"text":"Horatio" } ]
    }
  }
}

$ curl --anyauth --user user:password -X POST -d@./query.json -i \
    -H "Content-type: application/json" -H "Accept: application/json" \
    'http://localhost:8000/v1/values/speaker?options=index-options'

==> The distinct values of the SPEAKER element in element range index, for
    fragments that match the query "Yorick NEAR Horatio", expressed as a
    JSON structured query in the POST body. The results are returned as JSON.

{
  "values-response": {
    "name": "speaker",
    "type": "xs:string",
    "distinct-value": [
      ...
      {
        "frequency": 1,
        "_value": "HAMLET"
      },
      {
        "frequency": 1,
        "_value": "HORATIO"
      },
      {
        "frequency": 1,
        "_value": "KING CLAUDIUS"
      },
      ...
    ],
    "metrics": {
      "values-resolution-time": "PT0.002033S",
      "total-time": "PT0.004128S"
    }
  }
}

Example

Assume the following query options are installed with the name "index-options":

<options xmlns="http://marklogic.com/appservices/search">
    <values name="speaker">
        <range type="xs:string">
            <element ns="" name="SPEAKER"/>
        </range>
    </values>
</options>

$ cat query.xml
<search xmlns="http://marklogic.com/appservices/search">
  <query>
    <near-query>
      <term-query>
        <text>Yorick</text>
      </term-query>
      <term-query>
        <text>Horatio</text>
      </term-query>
    </near-query>
  </query>
  <options>
    <return-metrics>false</return-metrics>
  </options>
</search>

$ curl --anyauth --user user:password -X POST -d@./query.xml \
    -H "Content-type: application/xml" -i \
    'http://localhost:8000/v1/values/speaker?options=index-options

==> The distinct values of the SPEAKER element in element range index, for
    fragments that match the query "Yorick NEAR Horatio", expressed as an
    XML combined query in the POST body. Dynamic options in the combined
    query disable including metrics in the results. The results are returned 
    as XML.

<values-response name="speaker" type="xs:string" 
    xmlns="http://marklogic.com/appservices/search" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  ...
  <distinct-value frequency="1">HAMLET</distinct-value>
  <distinct-value frequency="1">HORATIO</distinct-value>
  <distinct-value frequency="1">KING CLAUDIUS</distinct-value>
  <distinct-value frequency="1">LAERTES</distinct-value>
  <distinct-value frequency="1">QUEEN GERTRUDE</distinct-value>
  <distinct-value frequency="1">Second Clown</distinct-value>
</values-response>

The following is the same combined query, expressed as JSON:

{
  "search" : {
    "query" : {
      "near-query" : {
        "term-query" : [ {"text" : "Yorick"}, {"text":"Horatio" } ]
      }
    },
    "options" : {
      "return-metrics" : false
    }
  }
}

Example

$ cat combined-query.xml
<search xmlns="http://marklogic.com/appservices/search">
  <options xmlns="http://marklogic.com/appservices/search">
    <constraint name="title">
      <word>
        <element ns="" name="TITLE" />
      </word>
    </constraint>
    <values name="speaker">
        <range type="xs:string">
            <element ns="" name="SPEAKER"/>
        </range>
    </values>
    <return-metrics>false</return-metrics>
  </options>
  <query xmlns="http://marklogic.com/appservices/search">
    <word-constraint-query>
      <constraint-name>title</constraint-name>
      <text>hamlet</text>
    </word-constraint-query>
  </query>
</search>

$ curl --anyauth --user user:password -X POST -d@./combined-query.xml \
    'http://localhost:8000/v1/values/speaker?limit=10&start=4&pageLength=3'

==> The 4th through the 6th values from the set of 10 distinct values
    retrieved from the SPEAKER lexicon, as XML. The results retrieved
    from the lexicon are constrained to those in documents with the word
    "hamlet" in the title.

HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 341
Connection: Keep-Alive
Keep-Alive: timeout=5

<values-response name="speaker" type="xs:string" 
    xmlns="http://marklogic.com/appservices/search" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <distinct-value frequency="1">CORNELIUS</distinct-value>
  <distinct-value frequency="1">Danes</distinct-value>
  <distinct-value frequency="1">First Ambassador</distinct-value>
</values-response>

The following is the equivalent POST body as JSON:

{ "search": {
    "query": {
      "word-constraint-query": {
        "constraint-name": "title",
        "text": "hamlet"
    } },
    "options": {
      "values": {
        "name": "speaker",
        "range": {
          "type": "xs:string",
          "element": { "name": "SPEAKER", "ns": ""}
        }
      },
      "constraint": {
        "name": "title",
        "word": {
          "element": { "name": "TITLE", "ns": "" }
        }
      },
      "return-metrics": false
    }
} }
Powered by MarkLogic Server | Terms of Use | Privacy Policy